.. _wms_vendor_parameters:

WMS vendor parameters
=====================

WMS vendor parameters are non-standard request parameters 
that are defined by an implementation to provide enhanced capabilities.
GeoServer supports a variety of vendor-specific parameters.

.. include:: ../generic_vendor_options.txt

GetCapabilities Request
-----------------------

format
^^^^^^

The ``format`` parameter can be used to request capabilities documents in a certain format. If the requested format is not supported the default format will be used.  
Refer to the GetCapabilities response for the list of supported formats, which differs according to the WMS version.

An example request:

  http://localhost:8080/geoserver/ows?service=wms&version=1.1.1&request=GetCapabilities&format=text/xml

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <WMT_MS_Capabilities version="1.1.1" updateSequence="247">
   	<Capability>
   		<Request>
   			<GetCapabilities>
   				<Format>application/vnd.ogc.wms_xml</Format>
   				<Format>text/xml</Format>
   ...


.. note::  
  Currently this parameter can only be used to request WMS 1.1.1 capabilities documents encoded in ``text/xml``, if used with other WMS versions or other formats it will have no effect.  ``application/json`` is not supported.


namespace
^^^^^^^^^

The ``namespace`` parameter causes WMS :ref:`wms_getcap` responses to be filtered to only contain layers in a particular namespace.  
The syntax is::

   namespace=<namespace>

where ``<namespace>`` is the namespace prefix.

.. warning::  Using an invalid namespace prefix will not cause an error, but the capabilities document returned will contain no layers, only layer groups.

.. note::  This affects the capabilities document only, not other requests. 
           Other WMS operations will still process all layers, even when a namespace is specified.

rootLayer
^^^^^^^^^

The ``rootLayer`` parameter can be used to request capabilities documents to include or not a top level root Layer container.
By default this top level root is always included as a parent of the configured layers and groups. The default can be changed at the service (WMS) level,
or at the layer / group level.

Using this parameter it is possible to exclude the default root when the resulting document has a single top element (e.g. a single group with nested children).
To do that, use the **false** value.

The parameter can also be used to override what is defined at the WMS or layer / group level. For example if the service is configure to exclude the Root element, we can force it
with **rootLayer=true**.



An example request:

  http://localhost:8080/geoserver/ows?service=wms&version=1.1.1&request=GetCapabilities&rootLayer=false

An example with XML POST:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <ogc:GetCapabilities xmlns:ogc="http://www.opengis.net/ows"
               xmlns:gml="http://www.opengis.net/gml"
      version="1.1.1" service="WMS" rootLayer="false">
   </ogc:GetCapabilities>



GetMap Request
--------------

angle
^^^^^

The ``angle`` parameter rotates the output map clockwise around its center. 
The syntax is::

   angle=<x>

where ``<x>`` is the number of degrees to rotate by.

Map rotation is supported in all raster formats, PDF, and SVG when using the Batik producer (which is the default).


buffer
^^^^^^

The ``buffer`` parameter specifies the number of additional border pixels that are used in the ``GetMap`` and ``GetFeatureInfo`` operations.  
The syntax is::

   buffer=<bufferwidth>

where ``<bufferwidth>`` is the width of the buffer in pixels.

In the :ref:`wms_getmap` operation, 
buffering includes features that lie outside the request bounding box, but whose styling is thick enough to be visible inside the map area.  

In the :ref:`wms_getfeatureinfo` operation,  
buffering creates a "search radius" around the location of the request.
Feature info is returned for features intersecting the search area.  
This is useful when working with an OpenLayers map (such as those generated by the :ref:`layerpreview` page) since it relaxes the need to click precisely on a point for the appropriate feature info to be returned.

In both operations GeoServer attempts to compute the ``buffer`` value automatically by inspecting the styles for each layer. 
All active symbolizers are evaluated, and the size of the largest is used (i.e. largest point symbolizer, thickest line symbolizer). 
Automatic buffer sizing cannot be computed if:

* the SLD contains sizes that are specified as feature attribute values
* the SLD contains external graphics and does not specify their size explicitly

In this event, the following defaults are used:

* 0 pixels for :ref:`wms_getmap` requests
* 5 pixels for :ref:`wms_getfeatureinfo` requests (a different min value can be set via the ``org.geoserver.wms.featureinfo.minBuffer`` system variable, e.g., add ``-Dorg.geoserver.wms.featureinfo.minBuffer=10`` to make the min buffer be 10 pixels)
  

If these are not sufficiently large, the explicit parameter can be used.

cql_filter
^^^^^^^^^^

The ``cql_filter`` parameter is similar to the standard ``filter`` parameter, but the filter is expressed using ECQL (Extended Common Query Language).  
ECQL provides a more compact and readable syntax compared to OGC XML filters.
For full details see the :ref:`filter_ecql_reference` and :ref:`cql_tutorial` tutorial.

If more than one layer is specified in the ``layers`` parameter, then a separate filter can be specified for each layer, separated by semicolons.
The syntax is::

   cql_filter=filter1;filter2...

An example of a simple CQL filter is::

   cql_filter=INTERSECTS(the_geom,%20POINT%20(-74.817265%2040.5296504))


sortBy
^^^^^^

The ``sortBy`` parameter allows to control the order of features/rasters displayed in the map, using the same
syntax as WFS 1.0, that is:

* ``&sortBy=att1 A|D,att2 A|D, ...`` for a single layer request
* ``&sortBy=(att1Layer1 A|D,att2Layer1 A|D, ...)(att1Layer2 A|D,att2Layer2 A|D, ...)...`` when requesting multiple layers

Care should be taken when using it as it has different behavior for raster layers, vector layers, and layer groups.
In particular:

* | For **raster layers**, ``sortBy`` maps to a "SORTING" read parameter that the reader might expose (image mosaic exposes such parameter).
  | In image mosaic, this causes the first granule found in the sorting will display on top, and then the others will follow.
  | Thus, to sort a scattered mosaic of satellite images so that the most recent image shows on top, and assuming the time attribute is called ``ingestion`` in the mosaic index, the specification will be ``&sortBy=ingestion D``.
* | For **vector layers**, ``sortBy`` maps to a sort by clause in the vector data source, and then painting happens using the normal "painter model" rules, so the first item returned is painted first, and then all others on top of it.
  | Thus, to sort a set of event points so that the most recent event is painted on top, and assuming the attribute is called "date" in the vector layer, the specification will be ``&sortBy=date`` or ``&sortBy=date A`` (ascending direction being the default one).
* | For **layer groups**, the sort specification is going to be copied over all internal layers, so the spec has to be valid for all of them, or an error will be reported. 
  | An empty spec can be used for layer groups in this case, for example, ``layers=theGroup,theLayer&sortBy=(),(date A)``


env
^^^

The ``env`` parameter defines the set of substitution values that can be used in SLD variable substitution. 
The syntax is::

  env=param1:value1;param2:value2;...

See :ref:`sld_variable_substitution` for more information.

featureid
^^^^^^^^^

The ``featureid`` parameter filters by feature ID, a unique value given to all features.  
Multiple features can be selected by separating the featureids by comma, as in this example::

   featureid=states.1,states.45  

filter
^^^^^^

The WMS specification allows only limited filtering of data.  
GeoServer enhances the WMS filter capability to match that provided by WFS.
The ``filter`` parameter can specify a list of OGC XML filters.  
The list is enclosed in parentheses: **( )**.  
When used in a GET request, the XML tag brackets must be URL-encoded.  

If more than one layer is specified in the ``layers`` parameter then a separate filter can be specified for each layer.

An example of an OGC filter encoded in a GET request is::

   filter=%3CFilter%20xmlns:gml=%22http://www.opengis.net/gml%22%3E%3CIntersects%3E%3CPropertyName%3Ethe_geom%3C/PropertyName%3E%3Cgml:Point%20srsName=%224326%22%3E%3Cgml:coordinates%3E-74.817265,40.5296504%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E

An example of an OGC filter encoding standard 2.0 in a GET request is::

   filter=%3Cfes%3AFilter%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20xmlns%3Agml%3D%22http%3A%2F%2Fwww.opengis.net%2Fgml%2F3.2%22%20xmlns%3Awfs%3D%22http%3A%2F%2Fwww.opengis.net%2Fwfs%22%20xmlns%3D%22http%3A%2F%2Fwww.opengis.net%2Ffes%2F2.0%22%20xmlns%3Afes%3D%22http%3A%2F%2Fwww.opengis.net%2Ffes%2F2.0%22%3E%3Cfes%3APropertyIsLike%20wildCard%3D%22*%22%20singleChar%3D%22.%22%20escapeChar%3D%22!%22%3E%3Cfes%3AValueReference%3ENAME%3C%2Ffes%3AValueReference%3E%3Cfes%3ALiteral%3E*United*%3C%2Ffes%3ALiteral%3E%3C%2Ffes%3APropertyIsLike%3E%3C%2Ffes%3AFilter%3E  

An example of an OGC filter encoding standard 2.0 ::
	
	<fes:Filter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:wfs="http://www.opengis.net/wfs" xmlns="http://www.opengis.net/fes/2.0" xmlns:fes="http://www.opengis.net/fes/2.0"><fes:PropertyIsLike wildCard="*" singleChar="." escapeChar="!"><fes:ValueReference>NAME</fes:ValueReference><fes:Literal>*United*</fes:Literal></fes:PropertyIsLike></fes:Filter>

.. _format_options:

format_options
^^^^^^^^^^^^^^

The ``format_options`` is a container for parameters that are format-specific. 
The syntax is::

    format_options=param1:value1;param2:value2;...

The supported format options are:

* ``antialias`` (values = ``on``, ``off``, ``text``): controls the use of antialiased rendering in raster output. 
* ``callback``: specifies the callback function name for the jsonp response format (default is ``parseResponse``).
* ``dpi``: sets the rendering DPI (dots-per-inch) for raster outputs. 
  The OGC standard output resolution is 90 DPI. 
  If you need to create high resolution images (e.g for printing) it is advisable to request a larger image size and specify a higher DPI. 
  In general, the image size should be increased by a factor equal to ``targetDPI/90``, with the target dpi set in the format options.
  For example, to print  a 100x100 image at 300 DPI request a 333x333 image with the DPI value set to 300: ``&width=333&height=333&format_options=dpi:300`` 
* ``layout``: specifies a layout name to use.  Layouts are used to add decorators such as compasses and legends.  This capability is discussed further in the :ref:`wms_decorations` section.
* ``quantizer`` (values = ``octree``, ``mediancut``): controls the color quantizer used to produce PNG8 images. GeoServer 2.2.0 provides two quantizers, a fast RGB quantizer called ``octree`` that does not handle translucency and a slower but more accurate RGBA quantizer called ``mediancut``. By default the first is used on opaque images, whilst the second is enabled if the client asks for a transparent image (``transparent=true``). This vendor parameter can be used to manually force the usage of a particular quantizer.
* ``timeout``: Apply a timeout value for a getMap request. If the timeout is reached, the getMap request is cancelled and an error is returned. The value used for the timeout will be the minimum of this format option and the global WMS timeout defined in the :ref:`wms_configuration`. A value of zero means no timeout.
* ``kmattr`` (values = ``true``, ``false``): determines whether the KML returned by GeoServer should include clickable attributes or not. This parameter primarily affects Google Earth rendering.  
* ``legend`` (values = ``true``, ``false``): KML may add the legend.
* ``kmscore`` (values = between ``0`` to force raster output and ``100`` to force vector output): parameter sets whether GeoServer should render KML data as vector or raster. This parameter primarily affects Google Earth rendering.  
* ``kmltitle``: parameter sets the KML title.
* ``kmlrefresh`` (values = greater than ``0`` or ``expires``): Force Network Link reload in refresh mode on interval of seconds.  When expires is specified client will refresh whenever the time has elapsed specified in cache expiration headers.  The caching time may be set in the Layer configuration under Publishing tab setting  HTTP Cache Time. This parameter primarily affects Google Earth rendering and is dependent on being respected by the client.  Using a second interval is a more reliable choice.  
* ``kmlvisible`` (values = ``true``, ``false``): Indicates whether layers selected will default to enabled or not. Default behavior is enabled. This parameter primarily affects Google Earth rendering.
* ``advancedProjectionHandling`` (values = ``true``, ``false``): Enable \ Disable advanced projection handling, if it is enabled in the GUI. If it is disabled in the GUI, this option has no effect.
* ``mapWrapping`` (values = ``true``, ``false``): Enable \ Disable continuous map wrapping, if it is enabled in the GUI. If it is disabled in the GUI, this option has no effect. Continuous map wrapping will also be disabled if ``advancedProjectionHandling`` is disabled.
* ``decorationsOnly`` (values = ``true``, ``false``): Disabled by default. When value is true, it allows to get a transparent sized image for the request on which maps are not rendered, but it keeps the decorations applied (if present).

maxFeatures and startIndex
^^^^^^^^^^^^^^^^^^^^^^^^^^

The parameters ``maxFeatures`` and ``startIndex`` can be used together to provide "paging" support.  
Paging is helpful in situations such as KML crawling, where it is desirable to be able to retrieve the map in sections when there are a large number of features.

The ``startindex=n`` parameter specifies the index from which to start rendering in an ordered list of features.
``n`` must be a positive integer.

The ``maxfeatures=n`` parameter sets a limit on the amount of features rendered.  
``n`` must be a positive integer.  
When used with ``startindex``, the features rendered will be the ones starting at the ``startindex`` value.

Note that not all layers support paging.
For a layer to be queried in this way, the underlying feature source must support paging.
This is usually the case for databases (such as PostGIS).

palette
^^^^^^^

It is sometimes advisable (for speed and bandwidth reasons) to downsample the bit depth of returned maps.  
The way to do this is to create an image with a limited color palette, and save it in the ``palettes`` directory inside your GeoServer Data Directory.  
It is then possible to specify the ``palette`` parameter of the form::

   palette=<image>

where ``<image>`` is the filename of the palette image (without the extension).  To force a web-safe palette, use the syntax ``palette=safe``.  
For more information see the tutorial on :ref:`tutorials_palettedimages`

propertyName
^^^^^^^^^^^^

The ``propertyName`` parameter specifies which properties are included in the response of the ``GetFeatureInfo`` operation. 
The syntax is the same as in the WFS ``GetFeature`` operation.  
For a request for a single layer the syntax is::

   propertyName=name1,...,nameN

For multiple layers the syntax is::

   propertyName=(nameLayer11,...,nameLayer1N)...(name1LayerN,...,nameNLayerN)

The nature of the properties depends on the layer type:
	
* For vector layers the names specify the feature attributes.
* For raster layers the names specify the bands.
* For cascaded WMS layers the names specify the GML properties to be returned by the remote server.

   
tiled
^^^^^

Meta-tiling prevents issues with duplicated labels when using a tiled client such as OpenLayers. 
When meta-tiling is used, images are rendered and then split into smaller tiles (by default in a 3x3 pattern) before being served.
In order for meta-tiling to work, the tile size *must* be set to 256x256 pixels, 
and the ``tiled`` and ``tilesorigin`` parameters must be specified.

The ``tiled`` parameter controls whether meta-tiling is used. 
The syntax is::

   tiled=[true|false]

To invoke meta-tiling use ``tiled=true``.

tilesorigin
^^^^^^^^^^^

The ``tilesorigin`` parameter is also required for meta-tiling.  
The syntax is::

   tilesorigin=x,y

where ``x`` and ``y`` are the coordinates of the lower left corner (the "origin") of the tile grid system. 

OpenLayers example
''''''''''''''''''

In OpenLayers, a good way to specify the ``tilesorigin`` is to reference the map  extents directly.

.. warning::  If the map extents are modified dynamically, the ``tilesorigin`` of each meta-tiled layer must be updated accordingly.

The following code shows how to specify the meta-tiling parameters:

.. code-block:: javascript 
   :linenos: 

    var options = {
        ...
        maxExtent: new OpenLayers.Bounds(-180, -90, 180, 90),
        ...
    };
    map = new OpenLayers.Map('map', options);
    
    tiled = new OpenLayers.Layer.WMS(
        "Layer name", "http://localhost:8080/geoserver/wms",
        {
            srs: 'EPSG:4326',
            width: 391,
            styles: '',
            height: 550,
            layers: 'layerName',
            format: 'image/png',
            tiled: true,
            tilesorigin: map.maxExtent.left + ',' + map.maxExtent.bottom
        },
        {buffer: 0} 
    );

scaleMethod
^^^^^^^^^^^

The ``scaleMethod`` parameter controls how the scale denominator is computed by GeoServer
The two possible values are:

  * ``OGC`` (default): the scale denominator is computed according to the OGC SLD specification, which
                       imposes simplified formulas for the sake of interoperability
  * ``Accurate``: use the full expressions for computing the scale denominator against geographic
                   data, taking into account the ellipsoidal shape of Earth
                 

The two methods tend to return values rather close to each other near the equator, but they
do diverge to larger differences as the latitude approaches the poles.

.. _wms_vendor_parameter_interpolations:

interpolations
^^^^^^^^^^^^^^

The ``interpolations`` parameter allows choosing a specific resampling (interpolation) method. 
It can be used in the ``GetMap`` operation. 

If more than one layer is specified in the ``layers`` parameter, then a separate interpolation method can be specified for each layer, separated by commas.
The syntax is::

   interpolations=method1,method2,... 

method<n> values can be one of the following: 

 * **nearest neighbor**
 * **bilinear**
 * **bicubic**

or empty if the default method has to be used for the related layer. 

The parameter allows to override the global *WMS Raster Rendering Options* setting (see :ref:`WMS Settings <services_webadmin_wms>` for more info), as well as the layer specific *Default Interpolation Method* publishing parameter (see :ref:`Layers <data_webadmin_layers>` for more info), on a layer by layer basis.

clip
^^^^

The ``clip`` parameter can be used to clip WMS response using a Polygon mask represented by a valid WKT String.

Here are two examples, the first one using WKT, the second using EWKT::

   clip=POLYGON((-14.50804652396198 55.579454354599356,34.53492222603802 55.579454354599356,34.53492222603802 32.400173313532584,-14.50804652396198 32.400173313532584,-14.50804652396198 55.579454354599356))
   clip=srid=900913;POLYGON ((-1615028.3514525702 7475148.401208023, 3844409.956787858 7475148.401208023, 3844409.956787858 3815954.983140064, -1615028.3514525702 3815954.983140064, -1615028.3514525702 7475148.401208023))

.. note::  
  The Axis order of WKT must be East/North regardless of WMS version.
  Currently this parameter is ignored for layers with Complex features.
